This document provides instructions for creating and building new parts with MrC for PowerPC and SCpp for 68K. Before reading this document, read the Installation Guide for MPW to properly configure your MPW and ODF environments.
Table of Contents
-------------------------
• Creating a New Part
• Using PartMaker
• Adding New Files to Your Project
• Adding Source Files
• Adding ODF Resource Files
• Adding IDL Files
• FWBuild Makefiles
• Updating Your 'nmap' Resources
• Building Your Part
• Running Your Part
• Building ODF
Creating a New Part
Whenever you want to create a new part, use PartMaker Pro to generate your initial project. PartMaker Pro is located in the PartMaker folder and contains seven templates: three for creating non-embedding parts based on the ODFHello, ODFForm, and ODFNothing examples; three for creating embedding parts based on ODFContainer, ODFEmbed, and ODFTable; and one to create a Cyberdog-savvy part. Choose the template whose features most closely match your part and do the following:
1) Use PartMaker Pro to generate a new project.
2) Add any new files to your project.
3) Update your Binding resources.
Note: Any parts you make must be created in the ODFDev folder. This is because the MPW make files assume that your project is located there.
Using PartMaker Pro
Simply double-click the PartMaker Pro application and follow the on-screen information. For more details you can read the 'PartMaker ReadMe' document located in the same folder.
Once you create your part, you should not change the part or company name. PartMaker Pro uses this information in the source code to uniquely identify your part to OpenDoc. If you need to change the name of the part, use PartMaker Pro again to create a new part and copy any new material you had written to the new project.
Once you have your new project (and before you add any new material to the part), launch MPW and build the part. This step allows you to verify that the part was generated correctly and does run. It also allows you to make an alias to the resulting part editor and add it to your Editors folder. See the section Building Your Part, later in this file, for more information on building your part editor.
Note: the two files called 'Part.Cust' and 'Part.Info' can be deleted. They are used by PartMaker Pro to generate your project and are not needed after that.
Adding New Files to Your Project
Once you have a new project, you can add new source files to this project by adding the files to your project makefile (MacMake.bmk). You can also add both native resource files (.r extension) and ODF cross-platform resource files (.fr extension).
Adding Source Files
To add a new .cpp file to your makefile, you have to add the corresponding object file to the list of Component Objects in your makefile. If you look at the MacMake.bmk file that came with your project, you will see a variable called __ComponentObjects, which is set to a series of files whose endings are .cpp.o. Each of these files is an object file that is generated from the corresponding .cpp file. When you add a file to this list, the ODF build system automatically compiles the source file and links the resulting object file into your part.
ODF puts object files in the directory specified by the _FWObjDir variable. You should put any new object files in this directory as well. Simply copy the syntax of an existing element in the __ComponentObjects list when adding new source files. For example if you add a new source file called MySourceFile.cpp, your makefile should look like the following:
__ComponentObjects = ∂
"{_FWObjDir}SOMPart.cpp.o ∂
"{_FWObjDir}MySourceFile.cpp.o ∂
... other source files...
If your source file relies on header files that are not located in your project's Sources folder, you will need to tell the ODF build system where these headers are. You do this by adding the header file directory to the __IncludeDirs list. By default, this list contains the directories for the ODF header files and for the directory containing your source files (specified by the _FWTargetDir variable).
Similarly, if you have header files that you use specifically when compiling IDL or Resource files, you can add the header directory to the __IDLIncludeDirs or __FWRCIncludeDirs variables, respectively. Note that the __FWRCIncludeDirs variable is used by both the Rez and ODFRC tools to locate header files.
Adding ODF Resource Files
ODF resource files are normal text files that have an .fr extension and contain ODF cross-platform resources. The ODFRC plugin compiles these files into binary resources, which then get linked into your part editor. To add a new resource file to your project, add the name of the resulting binary resource file to the __ComponentResources variable list. The name of the resource file must have the extension .rsrc for the build system to compile the resource. For example, if you define a resource file named MyViews.fr, your makefile should look like the following:
__ComponentResources = ∂
"{_FWObjDir}Part.rsrc ∂
"{_FWObjDir}MyViews.rsrc ∂
... other resource files...
You can add both ODF resource files (.fr extension) and platform-specific resource files (.r extension) in this way. ODF compiles each file using the appropriate tool, based on the filename extension.
If your resource file relies on header files that are not located in your project's Sources folder, add the directory containing the header file to the __FWRCIncludeDirs variable.
Using AppMaker for the Visual Editing of Views: See the AppMaker folder inside "Tools & Goodies" for a demo version of Bowers Development's AppMaker and information on how to use it with PartMaker to create your part's interface.
Adding IDL Files
The only time you should add IDL files is if your part defines an extension. You should NEVER modify ODF's IDL files or the IDL files that were generated by PartMaker; use C++ to modify the functionality of your part instead. If you are creating an extension for your part, you can simply add the IDL file(s) to your makefile and add the generated .cpp file(s) to your list of compilation targets.
For example, to add an IDL file called MyExtension.idl to your makefile, you would want to add the following dependencies to your makefile:
You would also add the MyExtension.cpp.o file to the list of Component Objects as you would for any other source file.
If your IDL file relies on header files that are not located in your project's Sources folder, add the header file directory to the __IDLIncludeDirs variable.
FWBuild MakeFiles
The FWBuild script works in conjunction with the MPW tool FWTool to compile the files of your project and output your part's shared library. To get a list of options for FWBuild, specify the -help option on the command line. FWBuild uses the compilation and make rules defined in the files MacMake.rul and MacMake.dfn to compile your source files and resources. You should not need to change the contents of these files. FWBuild, FWTool, MacMake.rul, and MacMake.dfn are all located in the "ODFDev:ODF:Tools:Mac:" folder.
The preceding sections described the process for adding source files to your part. This section explains the purpose of a few of the other variables declared in a standard ODF makefile for the Mac OS.
__ComponentName
This variable defines the name of the resulting part editor.
You also use this name in conjunction with a specific extension to build different portions of your project. The following is a list of extensions and the corresponding build target:
.CFM - Builds your part's shared library (the most common target).
.IDE - Compiles your part's resources and IDL files only.
.RSED - Compiles only the resource files (both Rez and ODFRC).
.SOM - Compiles only the IDL files (used by SOMobjects™ TS plugin for CodeWarrior)
.LIB - Builds your part into a static library instead of a dynamic library; otherwise identical to .CFM
For example, to build the shared library of a part called MyPart, you would issue the following statements on your MPW command line:
directory "{MyPartDirectory}"
FWBuild MyPart.CFM
__ComponentSignature
This variable defines the creator type of the part editor and is of type OSType.
__CFMInitFunction
Used internally to initialize your code fragments. DO NOT MODIFY!!
Updating Your 'nmap' Resources
Whenever you create a new part, PartMaker creates a set of 'nmap' resources for your part. However, because the content of your part is likely to be different than the default content of the PartMaker part, you must change these resources to reflect your part's content. See the "'nmap', Icon, & Part Signature" document in the "Documentation:Development Notes:" folder for more information on how to do this.
Building Your Part
For your convenience, all projects come with a special script, called Build, which builds your part's shared library. In your project folder, you will find folders for each of the possible project configurations. To build a debug version of your part for PowerPC, open the project file in the MCPPCDebug folder and execute the Build script. To build a debug version of your part for 68K, open the project file in the SC68KDebug folder and execute the Build script there. You can build release versions of your part by executing the Build script in the corresponding Release folder.
After MPW builds your part, make an alias to your part editor and put the alias in your Editors folder. If you do this, you will not have to copy your part to the Editors folder each time you recompile. The alias will automatically lead OpenDoc to the updated part editor file.
Note: Remember that you also have to have the ODFLibrary (or an alias to it) in your Editors folder as well. ODF parts will not run without this library being present.
Running Your Part
To run your part, you need to create a stationery file for your part editor. To do this, drop your part editor onto the OpenDoc launcher located inside the "System Folder:Extensions:OpenDoc Libraries" folder of your machine. OpenDoc creates a new stationery file for your part and puts it into your Stationery folder.
Double click your part's stationery file to launch your part in a new document. Or, drag your part’s stationery into a containing part (such as ODFDraw) to launch it as an embedded part.
When you ship your part, include the official ODFLibrary (release, fat version) with it. Users can copy this library into their Exensions folder; users should copy your part editor into their Editors folder. The use of aliases is only for developers to alleviate the need to copy the part editor to the Editors folder after each compile.
Building ODF
To rebuild ODF (debug version) enter the following line:
for Symantec
"{ODFDev}SC68KBuildAll" Debug Clean NoExamples
for MRC
"{ODFDev}MCPPCBuildAll" Debug Clean NoExamples
If you also want to rebuild all the ODF examples remove the NoExamples keyword
